<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
    <title>README.rdoc</title>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <link rel="stylesheet" href="../../css/reset.css" type="text/css" media="screen" />
<link rel="stylesheet" href="../../css/main.css" type="text/css" media="screen" />
<link rel="stylesheet" href="../../css/github.css" type="text/css" media="screen" />
<script src="../../js/jquery-1.3.2.min.js" type="text/javascript" charset="utf-8"></script>
<script src="../../js/jquery-effect.js" type="text/javascript" charset="utf-8"></script>
<script src="../../js/main.js" type="text/javascript" charset="utf-8"></script>
<script src="../../js/highlight.pack.js" type="text/javascript" charset="utf-8"></script>

</head>

<body>     
    <div class="banner">
        
            <span>Ruby on Rails v4.0.0</span><br />
        
        <h1>
            README.rdoc
        </h1>
        <ul class="files">
            
            <li>
                activemodel/README.rdoc
                
                    <a href="https://github.com/rails/rails/blob/068289f23933225acc2cff27e4ebe1a0afd8cb94/activemodel/README.rdoc" target="_blank" class="github_url">on GitHub</a>
                
            </li>
            <li>Last modified: 2013-06-25 14:39:21 +0000</li>
        </ul>
    </div>

    <div id="bodyContent">
        <div id="content">
  
    <div class="description">
      
<h1 id="label-Active+Model+--+model+interfaces+for+Rails">Active Model – model interfaces for <a href="../../classes/Rails.html">Rails</a></h1>

<p>Active Model provides a known set of interfaces for usage in model classes.
They allow for Action Pack helpers to interact with non-Active Record
models, for example. Active Model also helps with building custom ORMs for
use outside of the <a href="../../classes/Rails.html">Rails</a> framework.</p>

<p>Prior to <a href="../../classes/Rails.html">Rails</a> 3.0, if a plugin or
gem developer wanted to have an object interact with Action Pack helpers,
it was required to either copy chunks of code from <a
href="../../classes/Rails.html">Rails</a>, or monkey patch entire helpers
to make them handle objects that did not exactly conform to the Active
Record interface. This would result in code duplication and fragile
applications that broke on upgrades. Active Model solves this by defining
an explicit API. You can read more about the API in
<code>ActiveModel::Lint::Tests</code>.</p>

<p>Active Model provides a default module that implements the basic API
required to integrate with Action Pack out of the box:
<code>ActiveModel::Model</code>.</p>

<pre class="ruby"><span class="ruby-keyword">class</span> <span class="ruby-constant">Person</span>
  <span class="ruby-identifier">include</span> <span class="ruby-constant">ActiveModel</span><span class="ruby-operator">::</span><span class="ruby-constant">Model</span>

  <span class="ruby-identifier">attr_accessor</span> :<span class="ruby-identifier">name</span>, :<span class="ruby-identifier">age</span>
  <span class="ruby-identifier">validates_presence_of</span> :<span class="ruby-identifier">name</span>
<span class="ruby-keyword">end</span>

<span class="ruby-identifier">person</span> = <span class="ruby-constant">Person</span>.<span class="ruby-identifier">new</span>(<span class="ruby-identifier">name</span><span class="ruby-operator">:</span> <span class="ruby-string">'bob'</span>, <span class="ruby-identifier">age</span><span class="ruby-operator">:</span> <span class="ruby-string">'18'</span>)
<span class="ruby-identifier">person</span>.<span class="ruby-identifier">name</span>   <span class="ruby-comment"># =&gt; 'bob'</span>
<span class="ruby-identifier">person</span>.<span class="ruby-identifier">age</span>    <span class="ruby-comment"># =&gt; '18'</span>
<span class="ruby-identifier">person</span>.<span class="ruby-identifier">valid?</span> <span class="ruby-comment"># =&gt; true</span>
</pre>

<p>It includes model name introspections, conversions, translations and
validations, resulting in a class suitable to be used with Action Pack. See
<code>ActiveModel::Model</code> for more examples.</p>

<p>Active Model also provides the following functionality to have ORM-like
behavior out of the box:</p>
<ul><li>
<p>Add attribute magic to objects</p>

<pre class="ruby"><span class="ruby-keyword">class</span> <span class="ruby-constant">Person</span>
  <span class="ruby-identifier">include</span> <span class="ruby-constant">ActiveModel</span><span class="ruby-operator">::</span><span class="ruby-constant">AttributeMethods</span>

  <span class="ruby-identifier">attribute_method_prefix</span> <span class="ruby-string">'clear_'</span>
  <span class="ruby-identifier">define_attribute_methods</span> :<span class="ruby-identifier">name</span>, :<span class="ruby-identifier">age</span>

  <span class="ruby-identifier">attr_accessor</span> :<span class="ruby-identifier">name</span>, :<span class="ruby-identifier">age</span>

  <span class="ruby-keyword">def</span> <span class="ruby-identifier">clear_attribute</span>(<span class="ruby-identifier">attr</span>)
    <span class="ruby-identifier">send</span>(<span class="ruby-node">&quot;#{attr}=&quot;</span>, <span class="ruby-keyword">nil</span>)
  <span class="ruby-keyword">end</span>
<span class="ruby-keyword">end</span>

<span class="ruby-identifier">person</span>.<span class="ruby-identifier">clear_name</span>
<span class="ruby-identifier">person</span>.<span class="ruby-identifier">clear_age</span>
</pre>

<p><a href="../../classes/ActiveModel/AttributeMethods.html">Learn more</a></p>
</li><li>
<p>Callbacks for certain operations</p>

<pre class="ruby"><span class="ruby-keyword">class</span> <span class="ruby-constant">Person</span>
  <span class="ruby-identifier">extend</span> <span class="ruby-constant">ActiveModel</span><span class="ruby-operator">::</span><span class="ruby-constant">Callbacks</span>
  <span class="ruby-identifier">define_model_callbacks</span> :<span class="ruby-identifier">create</span>

  <span class="ruby-keyword">def</span> <span class="ruby-identifier">create</span>
    <span class="ruby-identifier">run_callbacks</span> :<span class="ruby-identifier">create</span> <span class="ruby-keyword">do</span>
      <span class="ruby-comment"># Your create action methods here</span>
    <span class="ruby-keyword">end</span>
  <span class="ruby-keyword">end</span>
<span class="ruby-keyword">end</span>
</pre>

<p>This generates <code>before_create</code>, <code>around_create</code> and
<code>after_create</code> class methods that wrap your create method.</p>

<p><a href="../../classes/ActiveModel/Callbacks.html">Learn more</a></p>
</li><li>
<p>Tracking value changes</p>

<pre class="ruby"><span class="ruby-keyword">class</span> <span class="ruby-constant">Person</span>
  <span class="ruby-identifier">include</span> <span class="ruby-constant">ActiveModel</span><span class="ruby-operator">::</span><span class="ruby-constant">Dirty</span>

  <span class="ruby-identifier">attr_accessor</span> :<span class="ruby-identifier">name</span>
<span class="ruby-keyword">end</span>

<span class="ruby-identifier">person</span> = <span class="ruby-constant">Person</span>.<span class="ruby-identifier">new</span>
<span class="ruby-identifier">person</span>.<span class="ruby-identifier">name</span>             <span class="ruby-comment"># =&gt; nil</span>
<span class="ruby-identifier">person</span>.<span class="ruby-identifier">changed?</span>         <span class="ruby-comment"># =&gt; false</span>
<span class="ruby-identifier">person</span>.<span class="ruby-identifier">name</span> = <span class="ruby-string">'bob'</span>
<span class="ruby-identifier">person</span>.<span class="ruby-identifier">changed?</span>         <span class="ruby-comment"># =&gt; true</span>
<span class="ruby-identifier">person</span>.<span class="ruby-identifier">changed</span>          <span class="ruby-comment"># =&gt; ['name']</span>
<span class="ruby-identifier">person</span>.<span class="ruby-identifier">changes</span>          <span class="ruby-comment"># =&gt; { 'name' =&gt; [nil, 'bob'] }</span>
<span class="ruby-identifier">person</span>.<span class="ruby-identifier">name</span> = <span class="ruby-string">'robert'</span>
<span class="ruby-identifier">person</span>.<span class="ruby-identifier">save</span>
<span class="ruby-identifier">person</span>.<span class="ruby-identifier">previous_changes</span> <span class="ruby-comment"># =&gt; {'name' =&gt; ['bob, 'robert']}</span>
</pre>

<p><a href="../../classes/ActiveModel/Dirty.html">Learn more</a></p>
</li><li>
<p>Adding <code>errors</code> interface to objects</p>

<p>Exposing error messages allows objects to interact with Action Pack helpers
seamlessly.</p>

<pre class="ruby"><span class="ruby-keyword">class</span> <span class="ruby-constant">Person</span>

  <span class="ruby-keyword">def</span> <span class="ruby-identifier">initialize</span>
    <span class="ruby-ivar">@errors</span> = <span class="ruby-constant">ActiveModel</span><span class="ruby-operator">::</span><span class="ruby-constant">Errors</span>.<span class="ruby-identifier">new</span>(<span class="ruby-keyword">self</span>)
  <span class="ruby-keyword">end</span>

  <span class="ruby-identifier">attr_accessor</span> :<span class="ruby-identifier">name</span>
  <span class="ruby-identifier">attr_reader</span>   :<span class="ruby-identifier">errors</span>

  <span class="ruby-keyword">def</span> <span class="ruby-identifier">validate!</span>
    <span class="ruby-identifier">errors</span>.<span class="ruby-identifier">add</span>(:<span class="ruby-identifier">name</span>, <span class="ruby-string">&quot;can not be nil&quot;</span>) <span class="ruby-keyword">if</span> <span class="ruby-identifier">name</span>.<span class="ruby-identifier">nil?</span>
  <span class="ruby-keyword">end</span>

  <span class="ruby-keyword">def</span> <span class="ruby-keyword">self</span>.<span class="ruby-identifier">human_attribute_name</span>(<span class="ruby-identifier">attr</span>, <span class="ruby-identifier">options</span> = {})
    <span class="ruby-string">&quot;Name&quot;</span>
  <span class="ruby-keyword">end</span>
<span class="ruby-keyword">end</span>

<span class="ruby-identifier">person</span>.<span class="ruby-identifier">errors</span>.<span class="ruby-identifier">full_messages</span>
<span class="ruby-comment"># =&gt; [&quot;Name can not be nil&quot;]</span>
</pre>

<p><a href="../../classes/ActiveModel/Errors.html">Learn more</a></p>
</li><li>
<p>Model name introspection</p>

<pre class="ruby"><span class="ruby-keyword">class</span> <span class="ruby-constant">NamedPerson</span>
  <span class="ruby-identifier">extend</span> <span class="ruby-constant">ActiveModel</span><span class="ruby-operator">::</span><span class="ruby-constant">Naming</span>
<span class="ruby-keyword">end</span>

<span class="ruby-constant">NamedPerson</span>.<span class="ruby-identifier">model_name</span>        <span class="ruby-comment"># =&gt; &quot;NamedPerson&quot;</span>
<span class="ruby-constant">NamedPerson</span>.<span class="ruby-identifier">model_name</span>.<span class="ruby-identifier">human</span>  <span class="ruby-comment"># =&gt; &quot;Named person&quot;</span>
</pre>

<p><a href="../../classes/ActiveModel/Naming.html">Learn more</a></p>
</li><li>
<p>Making objects serializable</p>

<p><a
href="../../classes/ActiveModel/Serialization.html">ActiveModel::Serialization</a>
provides a standard interface for your object to provide
<code>to_json</code> or <code>to_xml</code> serialization.</p>

<pre class="ruby"><span class="ruby-keyword">class</span> <span class="ruby-constant">SerialPerson</span>
  <span class="ruby-identifier">include</span> <span class="ruby-constant">ActiveModel</span><span class="ruby-operator">::</span><span class="ruby-constant">Serialization</span>

  <span class="ruby-identifier">attr_accessor</span> :<span class="ruby-identifier">name</span>

  <span class="ruby-keyword">def</span> <span class="ruby-identifier">attributes</span>
    {<span class="ruby-string">'name'</span> =<span class="ruby-operator">&gt;</span> <span class="ruby-identifier">name</span>}
  <span class="ruby-keyword">end</span>
<span class="ruby-keyword">end</span>

<span class="ruby-identifier">s</span> = <span class="ruby-constant">SerialPerson</span>.<span class="ruby-identifier">new</span>
<span class="ruby-identifier">s</span>.<span class="ruby-identifier">serializable_hash</span>   <span class="ruby-comment"># =&gt; {&quot;name&quot;=&gt;nil}</span>

<span class="ruby-keyword">class</span> <span class="ruby-constant">SerialPerson</span>
  <span class="ruby-identifier">include</span> <span class="ruby-constant">ActiveModel</span><span class="ruby-operator">::</span><span class="ruby-constant">Serializers</span><span class="ruby-operator">::</span><span class="ruby-constant">JSON</span>
<span class="ruby-keyword">end</span>

<span class="ruby-identifier">s</span> = <span class="ruby-constant">SerialPerson</span>.<span class="ruby-identifier">new</span>
<span class="ruby-identifier">s</span>.<span class="ruby-identifier">to_json</span>             <span class="ruby-comment"># =&gt; &quot;{\&quot;name\&quot;:null}&quot;</span>

<span class="ruby-keyword">class</span> <span class="ruby-constant">SerialPerson</span>
  <span class="ruby-identifier">include</span> <span class="ruby-constant">ActiveModel</span><span class="ruby-operator">::</span><span class="ruby-constant">Serializers</span><span class="ruby-operator">::</span><span class="ruby-constant">Xml</span>
<span class="ruby-keyword">end</span>

<span class="ruby-identifier">s</span> = <span class="ruby-constant">SerialPerson</span>.<span class="ruby-identifier">new</span>
<span class="ruby-identifier">s</span>.<span class="ruby-identifier">to_xml</span>              <span class="ruby-comment"># =&gt; &quot;&lt;?xml version=\&quot;1.0\&quot; encoding=\&quot;UTF-8\&quot;?&gt;\n&lt;serial-person...</span>
</pre>

<p><a href="../../classes/ActiveModel/Serialization.html">Learn more</a></p>
</li><li>
<p>Internationalization (i18n) support</p>

<pre class="ruby"><span class="ruby-keyword">class</span> <span class="ruby-constant">Person</span>
  <span class="ruby-identifier">extend</span> <span class="ruby-constant">ActiveModel</span><span class="ruby-operator">::</span><span class="ruby-constant">Translation</span>
<span class="ruby-keyword">end</span>

<span class="ruby-constant">Person</span>.<span class="ruby-identifier">human_attribute_name</span>(<span class="ruby-string">'my_attribute'</span>)
<span class="ruby-comment"># =&gt; &quot;My attribute&quot;</span>
</pre>

<p><a href="../../classes/ActiveModel/Translation.html">Learn more</a></p>
</li><li>
<p>Validation support</p>

<pre class="ruby"><span class="ruby-keyword">class</span> <span class="ruby-constant">Person</span>
  <span class="ruby-identifier">include</span> <span class="ruby-constant">ActiveModel</span><span class="ruby-operator">::</span><span class="ruby-constant">Validations</span>

  <span class="ruby-identifier">attr_accessor</span> :<span class="ruby-identifier">first_name</span>, :<span class="ruby-identifier">last_name</span>

  <span class="ruby-identifier">validates_each</span> :<span class="ruby-identifier">first_name</span>, :<span class="ruby-identifier">last_name</span> <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span><span class="ruby-identifier">record</span>, <span class="ruby-identifier">attr</span>, <span class="ruby-identifier">value</span><span class="ruby-operator">|</span>
    <span class="ruby-identifier">record</span>.<span class="ruby-identifier">errors</span>.<span class="ruby-identifier">add</span> <span class="ruby-identifier">attr</span>, <span class="ruby-string">'starts with z.'</span> <span class="ruby-keyword">if</span> <span class="ruby-identifier">value</span>.<span class="ruby-identifier">to_s</span>[<span class="ruby-value">0</span>] <span class="ruby-operator">==</span> <span class="ruby-string">z</span>
  <span class="ruby-keyword">end</span>
<span class="ruby-keyword">end</span>

<span class="ruby-identifier">person</span> = <span class="ruby-constant">Person</span>.<span class="ruby-identifier">new</span>
<span class="ruby-identifier">person</span>.<span class="ruby-identifier">first_name</span> = <span class="ruby-string">'zoolander'</span>
<span class="ruby-identifier">person</span>.<span class="ruby-identifier">valid?</span>  <span class="ruby-comment"># =&gt; false</span>
</pre>

<p><a href="../../classes/ActiveModel/Validations.html">Learn more</a></p>
</li><li>
<p>Custom validators</p>

<pre class="ruby"><span class="ruby-keyword">class</span> <span class="ruby-constant">ValidatorPerson</span>
  <span class="ruby-identifier">include</span> <span class="ruby-constant">ActiveModel</span><span class="ruby-operator">::</span><span class="ruby-constant">Validations</span>
  <span class="ruby-identifier">validates_with</span> <span class="ruby-constant">HasNameValidator</span>
  <span class="ruby-identifier">attr_accessor</span> :<span class="ruby-identifier">name</span>
<span class="ruby-keyword">end</span>

<span class="ruby-keyword">class</span> <span class="ruby-constant">HasNameValidator</span> <span class="ruby-operator">&lt;</span> <span class="ruby-constant">ActiveModel</span><span class="ruby-operator">::</span><span class="ruby-constant">Validator</span>
  <span class="ruby-keyword">def</span> <span class="ruby-identifier">validate</span>(<span class="ruby-identifier">record</span>)
    <span class="ruby-identifier">record</span>.<span class="ruby-identifier">errors</span>[:<span class="ruby-identifier">name</span>] = <span class="ruby-string">&quot;must exist&quot;</span> <span class="ruby-keyword">if</span> <span class="ruby-identifier">record</span>.<span class="ruby-identifier">name</span>.<span class="ruby-identifier">blank?</span>
  <span class="ruby-keyword">end</span>
<span class="ruby-keyword">end</span>

<span class="ruby-identifier">p</span> = <span class="ruby-constant">ValidatorPerson</span>.<span class="ruby-identifier">new</span>
<span class="ruby-identifier">p</span>.<span class="ruby-identifier">valid?</span>                  <span class="ruby-comment"># =&gt;  false</span>
<span class="ruby-identifier">p</span>.<span class="ruby-identifier">errors</span>.<span class="ruby-identifier">full_messages</span>    <span class="ruby-comment"># =&gt; [&quot;Name must exist&quot;]</span>
<span class="ruby-identifier">p</span>.<span class="ruby-identifier">name</span> = <span class="ruby-string">&quot;Bob&quot;</span>
<span class="ruby-identifier">p</span>.<span class="ruby-identifier">valid?</span>                  <span class="ruby-comment"># =&gt;  true</span>
</pre>

<p><a href="../../classes/ActiveModel/Validator.html">Learn more</a></p>
</li></ul>

<h2 id="label-Download+and+installation">Download and installation</h2>

<p>The latest version of Active Model can be installed with RubyGems:</p>

<pre>% [sudo] gem install activemodel</pre>

<p>Source code can be downloaded as part of the <a
href="../../classes/Rails.html">Rails</a> project on GitHub</p>
<ul><li>
<p><a
href="https://github.com/rails/rails/tree/master/activemodel">github.com/rails/rails/tree/master/activemodel</a></p>
</li></ul>

<h2 id="label-License">License</h2>

<p>Active Model is released under the MIT license:</p>
<ul><li>
<p><a
href="http://www.opensource.org/licenses/MIT">www.opensource.org/licenses/MIT</a></p>
</li></ul>

<h2 id="label-Support">Support</h2>

<p>API documentation is at</p>
<ul><li>
<p><a href="../../index.html">api.rubyonrails.org</a></p>
</li></ul>

<p>Bug reports and feature requests can be filed with the rest for the Ruby on
<a href="../../classes/Rails.html">Rails</a> project here:</p>
<ul><li>
<p><a
href="https://github.com/rails/rails/issues">github.com/rails/rails/issues</a></p>
</li></ul>

    </div>
  


  


  
  


  


  

  



  

    

    

    


    


    <!-- Methods -->
              </div>

    </div>
  </body>
</html>